---
title: Use Bun with Astro
description: Learn how to use Bun with your Astro site.
type: recipe
i18nReady: true
---

[Bun](https://bun.sh/) is an all-in-one JavaScript runtime & toolkit. See [Bun's documentation](https://bun.sh/docs) for more information.

:::caution
Bun recently made their first stable release. However, using Bun with Astro may reveal rough edges. Some integrations may not work as expected. Consult [Bun's official documentation for working with Astro](https://bun.sh/guides/ecosystem/astro) for details.

If you have any problems using Bun, please [open an Issue on GitHub with Bun directly](https://github.com/oven-sh/bun/issues/new/choose).
:::

## Prerequisites

- Bun installed locally on your machine. See the [installation instructions](https://bun.sh/docs/installation) in Bun's official documentation.

## Create a new Astro project with Bun

Create a new Astro project with Bun using the following `create-astro` command:

```bash
bunx create-astro@latest my-astro-project-using-bun
```

:::tip
You may also [create a new Astro project from any existing Astro GitHub repository](/en/install/auto/#starter-templates) using the `--template` flag:
```bash
bunx create-astro@latest my-astro-project-using-bun --template eliancodes/brutal
```
:::

## Install dependencies

If you're starting a new project using `bunx create-astro`, the CLI will automatically use Bun to install dependencies and you can skip this step.

Otherwise, you'll need to install your dependencies with Bun:

```bash
bun install
```

## Add Types

Bun publishes the [`@types/bun`](https://www.npmjs.com/package/@types/bun) package, containing the runtime types for Bun.

Install `@types/bun` using the following command:

```sh
bun add -d @types/bun
```

## Using Astro integrations

You can also use any of the official Astro integrations with the `astro add` command:

```bash
bunx astro add react
```

## Run Astro with Bun

:::note
Use the [`--bun` CLI flag](https://bun.sh/docs/cli/bunx#shebangs) before every `astro` command to use Bun's own runtime in place of Node.
:::

### Run the development server

To run the development server using Bun as the runtime, use the following command:

```bash
bunx --bun astro dev
```

### Building your site with Bun

To build your site using Bun as the runtime, use the following command:

```bash
bunx --bun astro build
```

Astro will output your site to the `dist/` directory. Then, you can serve your site using the `preview` command:

```bash
bunx --bun astro preview
```

## Add SSR with Bun

Since Bun features [Node.js API compatibility](https://bun.sh/docs/runtime/nodejs-apis), you can use any Astro adapter for [server-side rendering](/en/guides/server-side-rendering/) to your Astro project:

```bash
bunx astro add vercel
```

## Testing in Bun

Bun ships with a fast, built-in, Jest-compatible test runner through the `bun test` command. If you like to use that read [`bun test` documentation](https://bun.sh/docs/cli/test).

However, it is also possible to use Cypress or Playwright for a modern approach to testing web apps.

### Cypress

Cypress is a front-end testing tool and is on a mission to "make the testing experience enjoyable and generate developer happiness". This enables you to write end-to-end tests for your Astro site.

Install Cypress with the following command:

```bash
bun add cypress --dev
```

For the rest of the configuration and to start your first test, follow the rest of Cypress process in the [Astro Testing Guide](/en/guides/testing/#configuration).

### Playwright

Playwright is an end-to-end testing framework that allows you to test your Astro code on all modern rendering engines including Chromium, WebKit, and Firefox.

Install Playwright using the following command:

```bash
bun create playwright
```

To create your first Playwright test, follow the instructions for the rest of the Playwright process in the [Astro Testing Guide](/en/guides/testing/#create-your-first-playwright-test).

## Official Resources

- [Build an app with Astro and Bun](https://bun.sh/guides/ecosystem/astro)

## Community Resources

Using Bun with Astro? Add your blog post or video to this page!

- [Building a Cloudflare Pages site with Bun](https://blog.otterlord.dev/posts/hello-from-bun/) - blog post
